home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / awt / Dialog.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  14.0 KB  |  442 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Dialog.java    1.53 98/08/12
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.peer.DialogPeer;
  17. import java.awt.event.*;
  18. import java.io.ObjectOutputStream;
  19. import java.io.ObjectInputStream;
  20. import java.io.IOException;
  21.  
  22.  
  23. /**
  24.  * A Dialog is a top-level window with a title and a border
  25.  * that is typically used to take some form of input from the user.
  26.  *
  27.  * The size of the dialog includes any area designated for the
  28.  * border.  The dimensions of the border area can be obtained 
  29.  * using the <code>getInsets</code> method, however, since 
  30.  * these dimensions are platform-dependent, a valid insets
  31.  * value cannot be obtained until the dialog is made displayable
  32.  * by either calling <code>pack</code> or <code>show</code>. 
  33.  * Since the border area is included in the overall size of the
  34.  * dialog, the border effectively obscures a portion of the dialog,
  35.  * constraining the area available for rendering and/or displaying
  36.  * subcomponents to the rectangle which has an upper-left corner
  37.  * location of <code>(insets.left, insets.top)</code>, and has a size of
  38.  * <code>width - (insets.left + insets.right)</code> by 
  39.  * <code>height - (insets.top + insets.bottom)</code>. 
  40.  * <p>
  41.  * The default layout for a dialog is BorderLayout.
  42.  * <p>
  43.  * A dialog must have either a frame or another dialog defined as its
  44.  * owner when it's constructed.  When the owner window of a visible dialog
  45.  * is hidden or minimized, the dialog will automatically be hidden
  46.  * from the user. When the owner window is subsequently re-opened, then
  47.  * the dialog is made visible to the user again.
  48.  * <p>
  49.  * A dialog can be either modeless (the default) or modal.  A modal
  50.  * dialog is one which blocks input to all other toplevel windows
  51.  * in the app context, except for any windows created with the dialog
  52.  * as their owner. 
  53.  * <p>
  54.  * Dialogs are capable of generating the following window events:
  55.  * WindowOpened, WindowClosing, WindowClosed, WindowActivated,
  56.  * WindowDeactivated.
  57.  *
  58.  * @see WindowEvent
  59.  * @see Window#addWindowListener
  60.  *
  61.  * @version     1.53, 08/12/98
  62.  * @author     Sami Shaio
  63.  * @author     Arthur van Hoff
  64.  * @since       JDK1.0
  65.  */
  66. public class Dialog extends Window {
  67.  
  68.     static {
  69.         /* ensure that the necessary native libraries are loaded */
  70.     Toolkit.loadLibraries();
  71.         initIDs();
  72.     }
  73.  
  74.     /**
  75.      * A dialogs resizable property. Will be true
  76.      * if the Dialog is to be resizable, otherwise
  77.      * it will be false.
  78.      *
  79.      * @serial
  80.      * @see setResizable()
  81.      */
  82.     boolean resizable = true;
  83.     /**
  84.      * Will be true if the Dialog is modal,
  85.      * otherwise the dialog will be modeless.
  86.      * A modal Dialog grabs all the input to
  87.      * the owner frame from the user.
  88.      *
  89.      * @serial
  90.      * @see isModal()
  91.      * @see setModal()
  92.      */
  93.     boolean modal;
  94.     /**
  95.      * Specifies the title of the Dialog.
  96.      * This field can be null.
  97.      *
  98.      * @serial
  99.      * @see getTitle()
  100.      * @see setTitle()
  101.      */
  102.     String title;
  103.  
  104.     private static final String base = "dialog";
  105.     private static int nameCounter = 0;
  106.  
  107.     /*
  108.      * JDK 1.1 serialVersionUID
  109.      */
  110.     private static final long serialVersionUID = 5920926903803293709L;
  111.  
  112.     /**
  113.      * Constructs an initially invisible, non-modal Dialog with 
  114.      * an empty title and the specified owner frame.
  115.      * @param owner the owner of the dialog
  116.      * @exception java.lang.IllegalArgumentException if <code>owner</code>
  117.      *            is <code>null</code>
  118.      * @see Component#setSize
  119.      * @see Component#setVisible
  120.      */
  121.     public Dialog(Frame owner) {
  122.     this(owner, "", false);
  123.     }
  124.  
  125.     /**
  126.      * Constructs an initially invisible Dialog with an empty title,
  127.      * the specified owner frame and modality.
  128.      * @param owner the owner of the dialog
  129.      * @param modal if true, dialog blocks input to other app windows when shown
  130.      * @exception java.lang.IllegalArgumentException if <code>owner</code>
  131.      *            is <code>null</code>
  132.      */
  133.     public Dialog(Frame owner, boolean modal) {
  134.     this(owner, "", modal);
  135.     }
  136.  
  137.     /**
  138.      * Constructs an initially invisible, non-modal Dialog with 
  139.      * the specified owner frame and title. 
  140.      * @param owner the owner of the dialog
  141.      * @param title the title of the dialog. A <code>null</code> value
  142.      *        will be accepted without causing a NullPointerException
  143.      *        to be thrown.
  144.      * @exception java.lang.IllegalArgumentException if <code>owner</code>
  145.      *            is <code>null</code>
  146.      * @see Component#setSize
  147.      * @see Component#setVisible
  148.      */
  149.     public Dialog(Frame owner, String title) {
  150.     this(owner, title, false);
  151.     }
  152.  
  153.     /**
  154.      * Constructs an initially invisible Dialog with the
  155.      * specified owner frame, title, and modality. 
  156.      * @param owner the owner of the dialog
  157.      * @param title the title of the dialog. A <code>null</code> value
  158.      *        will be accepted without causing a NullPointerException
  159.      *        to be thrown.
  160.      * @param modal if true, dialog blocks input to other app windows when shown
  161.      * @exception java.lang.IllegalArgumentException if <code>owner</code>
  162.      *            is <code>null</code>
  163.      * @see Component#setSize
  164.      * @see Component#setVisible
  165.      */
  166.     public Dialog(Frame owner, String title, boolean modal) {
  167.     super(owner);
  168.     if (owner == null) {
  169.         throw new IllegalArgumentException("null owner frame");
  170.     }
  171.     this.title = title;
  172.     this.modal = modal;
  173.     }
  174.  
  175.  
  176.     /**
  177.      * Constructs an initially invisible, non-modal Dialog with 
  178.      * an empty title and the specified owner dialog.
  179.      * @param owner the owner of the dialog
  180.      * @exception java.lang.IllegalArgumentException if <code>owner</code>
  181.      *            is <code>null</code>
  182.      * @since JDK1.2
  183.      */
  184.     public Dialog(Dialog owner) {
  185.     this(owner, "", false);
  186.     }
  187.  
  188.     /**
  189.      * Constructs an initially invisible, non-modal Dialog 
  190.      * with the specified owner dialog and title. 
  191.      * @param owner the owner of the dialog
  192.      * @param title the title of the dialog. A <code>null</code> value
  193.      *        will be accepted without causing a NullPointerException
  194.      *        to be thrown.
  195.      * @exception java.lang.IllegalArgumentException if <code>owner</code>
  196.      *            is <code>null</code>
  197.      * @since JDK1.2
  198.      */
  199.     public Dialog(Dialog owner, String title) {
  200.     this(owner, title, false);
  201.     }
  202.  
  203.     /**
  204.      * Constructs an initially invisible Dialog with the
  205.      * specified owner dialog, title, and modality. 
  206.      * @param owner the owner of the dialog
  207.      * @param title the title of the dialog. A <code>null</code> value
  208.      *        will be accepted without causing a NullPointerException to
  209.      *        be thrown.
  210.      * @param modal if true, dialog blocks input to other app windows when shown
  211.      * @exception java.lang.IllegalArgumentException if <code>owner</code>
  212.      *            is <code>null</code>
  213.      * @since JDK1.2
  214.      */
  215.     public Dialog(Dialog owner, String title, boolean modal) {
  216.     super(owner);
  217.     if (owner == null) {
  218.         throw new IllegalArgumentException("null owner dialog");
  219.     }
  220.     this.title = title;
  221.     this.modal = modal;
  222.     }
  223.  
  224.     /**
  225.      * Construct a name for this component.  Called by getName() when the
  226.      * name is null.
  227.      */
  228.     String constructComponentName() {
  229.         synchronized (getClass()) {
  230.         return base + nameCounter++;
  231.     }
  232.     }
  233.  
  234.     /**
  235.      * Makes this Dialog displayable by connecting it to
  236.      * a native screen resource.  Making a dialog displayable will
  237.      * cause any of its children to be made displayable.
  238.      * This method is called internally by the toolkit and should
  239.      * not be called directly by programs.
  240.      * @see Component#isDisplayable
  241.      * @see #removeNotify
  242.      */
  243.     public void addNotify() {
  244.     synchronized (getTreeLock()) {
  245.         if (peer == null) {
  246.             peer = getToolkit().createDialog(this);
  247.         }
  248.         super.addNotify();
  249.     }
  250.     }
  251.  
  252.     /**
  253.      * Indicates whether the dialog is modal.
  254.      * When a modal Dialog is made visible, user input will be
  255.      * blocked to the other windows in the app context, except for
  256.      * any windows created with this dialog as their owner.
  257.      *   
  258.      * @return    <code>true</code> if this dialog window is modal;
  259.      *            <code>false</code> otherwise.
  260.      * @see       java.awt.Dialog#setModal
  261.      */
  262.     public boolean isModal() {
  263.     return modal;
  264.     }
  265.  
  266.     /**
  267.      * Specifies whether this dialog should be modal.  
  268.      * @see       java.awt.Dialog#isModal
  269.      * @since     JDK1.1
  270.      */
  271.     public void setModal(boolean b) {
  272.     this.modal = b;
  273.     }
  274.  
  275.     /**
  276.      * Gets the title of the dialog. The title is displayed in the
  277.      * dialog's border.
  278.      * @return    the title of this dialog window. The title may be
  279.      *            <code>null</code>.
  280.      * @see       java.awt.Dialog#setTitle
  281.      */
  282.     public String getTitle() {
  283.     return title;
  284.     }
  285.  
  286.     /**
  287.      * Sets the title of the Dialog.
  288.      * @param title the title displayed in the dialog's border
  289.      * @see #getTitle
  290.      */
  291.     public synchronized void setTitle(String title) {
  292.     this.title = title;
  293.     DialogPeer peer = (DialogPeer)this.peer;
  294.     if (peer != null) {
  295.         peer.setTitle(title);
  296.     }
  297.     }
  298.  
  299.    /**
  300.      * Makes the Dialog visible. If the dialog and/or its owner
  301.      * are not yet displayable, both are made displayable.  The 
  302.      * dialog will be validated prior to being made visible.  
  303.      * If the dialog is already visible, this will bring the dialog 
  304.      * to the front.
  305.      * <p>
  306.      * If the dialog is modal, this call will block until the 
  307.      * dialog is hidden by calling <code>hide</code> or <code>dispose</code>. 
  308.      * It is permissible to show modal dialogs from the event 
  309.      * dispatching thread because the toolkit
  310.      * will ensure that another dispatching thread will run while
  311.      * the one which invoked this method is blocked. 
  312.      * @see Component#hide
  313.      * @see Component#isDisplayable
  314.      * @see Component#validate
  315.      * @see java.awt.Dialog#isModal
  316.      */
  317.     public void show() {
  318.     synchronized(getTreeLock()) {
  319.             if (parent != null && parent.getPeer() == null) {
  320.                 parent.addNotify();
  321.             }
  322.         if (peer == null) {
  323.         addNotify();
  324.         }
  325.     }
  326.     validate();        
  327.     if (visible) {
  328.         toFront();
  329.     } else {
  330.         visible = true;
  331.         if (isModal()) {
  332.         EventQueue modalQueue = null;
  333.         EventQueue currentQueue = Toolkit.getEventQueue();
  334.         synchronized (currentQueue) {
  335.             if (currentQueue.isDispatchThread()) {
  336.                 modalQueue = (EventQueue)
  337.                 java.security.AccessController.doPrivileged(
  338.                     new java.security.PrivilegedAction() {
  339.                         public Object run() {
  340.                         EventQueue eventQueue;
  341.                     String eqName = Toolkit.getProperty(
  342.                         "AWT.EventQueueClass",
  343.                         "java.awt.EventQueue");
  344.                     try {
  345.                         eventQueue = (EventQueue)
  346.                             Class.forName(eqName).
  347.                             newInstance();
  348.                     } catch (Exception e) {
  349.                         System.err.println(
  350.                             "Failed loading " + eqName +
  351.                         ": " + e);
  352.                         eventQueue = new EventQueue();
  353.                     }
  354.                     return eventQueue;
  355.                     }
  356.                 });
  357.             currentQueue.push(modalQueue);
  358.             }
  359.         }
  360.  
  361.                 // For modal case, we most post this event before calling
  362.                 // show, since calling peer.show() will block; this is not
  363.                 // ideal, as the window isn't yet visible on the screen...
  364.                 if ((state & OPENED) == 0) {
  365.                     postWindowEvent(WindowEvent.WINDOW_OPENED);
  366.                     state |= OPENED;
  367.                 }
  368.         peer.show(); // blocks until dialog brought down
  369.         if (modalQueue != null) {
  370.             // If we wait for currentQueue.pop() to call
  371.             // stopDispatching(), we deadlock waiting for the
  372.             // disposal to complete, as it waits to post an event.
  373.             // So, we explicitly call stopDispatching() here.
  374.             modalQueue.getDispatchThread().stopDispatching();
  375.             currentQueue.pop();
  376.         }
  377.         } else {
  378.             peer.show();
  379.                 if ((state & OPENED) == 0) {
  380.                     postWindowEvent(WindowEvent.WINDOW_OPENED);
  381.                     state |= OPENED;
  382.                 }
  383.         }
  384.     }
  385.     }
  386.  
  387.     /**
  388.      * Indicates whether this dialog is resizable by the user.
  389.      * @return    <code>true</code> if the user can resize the dialog;
  390.      *            <code>false</code> otherwise.
  391.      * @see       java.awt.Dialog#setResizable
  392.      */
  393.     public boolean isResizable() {
  394.     return resizable;
  395.     }
  396.  
  397.     /**
  398.      * Sets whether this dialog is resizable by the user.
  399.      * @param     resizable <code>true</code> if the user can
  400.      *                 resize this dialog; <code>false</code> otherwise.
  401.      * @see       java.awt.Dialog#isResizable
  402.      */
  403.     public void setResizable(boolean resizable) {
  404.         boolean testvalid = false;
  405.  
  406.         synchronized (this) {
  407.             this.resizable = resizable;
  408.             DialogPeer peer = (DialogPeer)this.peer;
  409.             if (peer != null) {
  410.                 peer.setResizable(resizable);
  411.                 testvalid = true;
  412.             }
  413.         }
  414.  
  415.         // On some platforms, changing the resizable state affects
  416.         // the insets of the Dialog. If we could, we'd call invalidate()
  417.         // from the peer, but we need to guarantee that we're not holding
  418.         // the Dialog lock when we call invalidate().
  419.         if (testvalid && valid) {
  420.             invalidate();
  421.         }
  422.     }
  423.  
  424.     /**
  425.      * Returns the parameter string representing the state of this
  426.      * dialog window. This string is useful for debugging.
  427.      * @return    the parameter string of this dialog window.
  428.      */
  429.     protected String paramString() {
  430.     String str = super.paramString() + (modal ? ",modal" : ",modeless");
  431.     if (title != null) {
  432.         str += ",title=" + title;
  433.     }
  434.     return str;
  435.     }
  436.  
  437.     /**
  438.      * Initialize JNI field and method IDs
  439.      */
  440.     private static native void initIDs();
  441. }
  442.